# RDP remote desktop ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- **RDP (Remote Desktop Protocol)** is a graphical remote desktop connection method. A Windows host can use the built-in "Remote Desktop Connection" tool to access the Quectel Pi M2 Debian desktop and view or control the graphical interface remotely. Quectel Pi M2 primarily uses the **GNOME** desktop environment, which can provide RDP remote desktop functionality via **GNOME Remote Desktop**, without the need to install additional software such as VNC, Xvfb, or x11vnc. > 💡 Note: When M2 uses the GNOME user desktop sharing method to connect via RDP, the graphical desktop session must remain in a logged-in state. # Preparation 1. **Confirm the device environment:** - Quectel Pi M2 has booted into the Debian system; - The Windows host and the development board are on the same network segment or within the same reachable local area network; - The Windows host has the "Remote Desktop Connection" tool installed or enabled. 2. **It is recommended to enter the development board via the serial console.** For detailed instructions on serial connection, please refer to debug_uart.md. For the M2 default login user, please follow the guide to use the account and password you created. If a local debugging environment is already available, you can also enter the system via ADB. 3. **Obtain the device IP address.** Execute on the development board: ```bash hostname -I ``` Record the IP address on the current network, which will be needed later for the Windows Remote Desktop Connection. > 💡 Note: The Windows host and the development board need to be on the same network segment or within the same local area network, and the networks on both ends must be able to reach each other. Otherwise, even if the RDP service has been started on the board side, the connection will not work. # GNOME Remote Desktop ## Software Installation The Quectel Pi M2 Debian system already has `gnome-remote-desktop` integrated, which can directly use GNOME Remote Desktop to provide RDP remote desktop functionality. You can execute the following command in the terminal to confirm whether the package is installed: ```bash dpkg -l | grep gnome-remote-desktop ``` If the package is not installed in the system, you can execute the following command to install it: ```bash sudo apt update sudo apt install -y gnome-remote-desktop ``` You can also execute the following command to confirm whether the remote desktop management tool exists: ```bash which grdctl ``` If the command returns `/usr/bin/grdctl`, it means the system already includes the GNOME remote desktop management tool. ## Software Configuration 1. **Graphical Interface Configuration** Through the Quectel Pi M2 graphical interface, navigate to: Settings > System > Remote Desktop.In the remote desktop settings interface, you can toggle the following switches according to actual usage needs: - **Desktop Sharing**: Allows other devices to view the current desktop via the RDP protocol. - **Remote Control**: Allows the remote connecting end to control the mouse and keyboard. ```{image} images/image_YtVCbZiK8oWqJ3xBrb8c6MMynSh.webp :width: 1113px :height: 626px ``` 2. **Command-Line Configuration** To configure RDP via the command line, execute the following commands in the user environment where the graphical desktop is logged in. The following example sets the RDP username and password to `q`; please modify as needed in actual use: ```bash mkdir -p ~/.local/share/gnome-remote-desktop openssl req -x509 -newkey rsa:2048 -nodes \ -keyout ~/.local/share/gnome-remote-desktop/rdp-tls.key \ -out ~/.local/share/gnome-remote-desktop/rdp-tls.crt \ -days 3650 -subj /CN=Quectel-Pi-M2 chmod 600 ~/.local/share/gnome-remote-desktop/rdp-tls.key grdctl rdp set-tls-cert ~/.local/share/gnome-remote-desktop/rdp-tls.crt grdctl rdp set-tls-key ~/.local/share/gnome-remote-desktop/rdp-tls.key grdctl rdp set-credentials q q grdctl rdp disable-view-only grdctl rdp enable systemctl --user restart gnome-remote-desktop.service ``` ## Software Startup After turning on **Desktop Sharing** in the graphical interface, the GNOME remote desktop service will be enabled automatically. You can also use the following command in the terminal to view the current status: ```bash grdctl status --show-credentials ``` Under normal circumstances, you can see RDP-related status, port, username, and remote control mode information. You can also check the user service and port listening status: ```bash systemctl --user status gnome-remote-desktop.service --no-pager -l ss -tulnp | grep -E ':3389|:3390' ``` > 💡 Note: If the system-level GNOME Remote Desktop has already occupied port `3389`, the desktop sharing service of the currently logged-in user may negotiate to another port, such as `3390`. Please refer to the actual output of `grdctl status --show-credentials` and `ss -tulnp`. If you need to enable the RDP backend via the command line, you can execute: ```bash grdctl rdp enable ``` If you need to allow the remote end to control the mouse and keyboard, you can execute: ```bash grdctl rdp disable-view-only ``` If you only want to allow the remote end to view the desktop without controlling the mouse and keyboard, you can execute: ```bash grdctl rdp enable-view-only ``` > 💡 Note: In actual use, it is recommended to prioritize configuration through the graphical interface to avoid inconsistency between command-line configuration and the displayed interface status. # Remote Desktop Connection 1. Open "Remote Desktop Connection" on the Windows host. 2. In the "Computer" input box, enter the IP address of the development board, for example ``. If you need to manually specify a port, you can enter `:3389`. If `grdctl status --show-credentials` or `ss -tulnp` shows that the RDP is actually listening on a different port, such as `3390`, then enter `:3390`. ```{image} images/image_F0m1b51YZohQu7x9ejccfrhgnDg.webp :width: 407px :height: 245px ``` 3. Click "Connect", and enter the username and password shown in the remote desktop settings interface as prompted. If Windows Security Center prompts for credentials, you can click **More choices**, select **Use a different account**, and then enter the username and password configured in the remote desktop settings interface. ```{image} images/image_CECJbRbt0oItfIx7jwvc7nHdnyh.webp :width: 456px :height: 580px ``` 4. After a successful connection, you can view and operate the Debian desktop on the Windows host. ```{image} images/image_J998bBNNwoG3kIxYW3Lc5yatnLd.webp :width: 1280px :height: 823px ``` # Troubleshooting | **Issue** | **Possible Cause** | **Resolution** | | --- | --- | --- | | Windows Remote Desktop cannot connect | Windows host and device are not on the same local network | Confirm network connections on both ends, and re-obtain the device's IP address | | Windows Remote Desktop cannot connect | Incorrect IP address or port | Run `hostname -I` on the device to confirm the IP, and run `grdctl status --show-credentials`, `ss -tulnp \| grep -E ':3389\|:3390'` to confirm the actual listening port | | Windows Remote Desktop cannot connect | **Desktop Sharing** is not enabled | Go to `Settings > System > Remote Desktop` and turn on **Desktop Sharing** | | Windows Remote Desktop cannot connect | GNOME Remote Desktop is not installed or not started | Run `which grdctl`, `grdctl status --show-credentials`, `systemctl --user status gnome-remote-desktop.service --no-pager -l` to confirm the installation and service status | | Can only view the desktop, cannot control the mouse and keyboard | **Remote Control** is not enabled, or it is currently in read-only mode | Turn on **Remote Control**, or run `grdctl rdp disable-view-only` | | Login prompts that the username or password is incorrect | The entered credentials do not match what is shown in the remote desktop settings | Use the username and password shown in the remote desktop settings interface; regenerate or manually modify the password if necessary | | Connection disconnects shortly after, and returns to the development board login screen | The current graphical desktop user session has exited, and the GNOME Remote Desktop user service stopped with the session | Re-log in to the graphical desktop on the development board locally, then confirm that `Unit status` in `grdctl status --show-credentials` is `active`, and reconnect | | Screen is abnormal or does not refresh after connection | The graphical desktop session state is abnormal | Confirm that the device has logged in to the graphical desktop, disconnect and reconnect | | Cannot connect after network switch | The device IP address has changed | Re-run `hostname -I` to obtain the current IP address, and update the connection address in Windows Remote Desktop |